eDocs Home > BEA AquaLogic Data Services Platform 3.0 Documentation > Data Services Developer's Guide

How To Add a Read Function

This topic describes how to add a read function to a logical entity service visually, in AquaLogic Data Services Studio.

Overview

A read function in a logical entity service retrieves data from underlying data sources, either physical or logical, and returns XML elements in the shape of the service's return type. You can build a logical service without a read function. However, the service must have at least one read function, marked primary, to have an update map. Only one read function in a service can be primary.

A read function is associated with exactly one XML schema, which is the service's return type. The read function must return the return type, but cannot take any other actions or have any side effects.

When you create a primary read function visually in Data Services Studio, ALDSP generates a pragma annotation and XQuery source. The pragma looks something like this:

(::pragma  function <f:function kind="read" visibility="public" isPrimary="true" xmlns:f="urn:annotations.ld.bea.com"/>::)

The initial XQuery source, before you map data types in Query Map view, shows that the read function returns an instance of the service's return type:

declare function tns:read() as element(tns:CustomerAndAddress)*{
    <tns:CustomerAndAddress>
        <CUSTOMER>
            <CUSTOMER_ID></CUSTOMER_ID>
            <FIRST_NAME></FIRST_NAME>
            <LAST_NAME></LAST_NAME>
            <SSN?></SSN>
            {
                <ADDRESS>
                    <ADDR_ID></ADDR_ID>
                    <CUSTOMER_ID></CUSTOMER_ID>
                    <FIRST_NAME></FIRST_NAME>
                    <ZIPCODE></ZIPCODE>
                    <COUNTRY></COUNTRY>
                </ADDRESS>
            }
        </CUSTOMER>
    </tns:CustomerAndAddress>
};

At this point, the return type has no values. The values are added after you map data sources to the return type in Query Map view:

declare function tns:read() as element(tns:CustomerAndAddress)*{
for $CUSTOMER in cus1:CUSTOMER()
return
        <tns:CustomerAndAddress>
            <CUSTOMER>
                <CUSTOMER_ID>{fn:data($CUSTOMER/CUSTOMER_ID)}</CUSTOMER_ID>
                <FIRST_NAME>{fn:data($CUSTOMER/FIRST_NAME)}</FIRST_NAME>
                <LAST_NAME>{fn:data($CUSTOMER/LAST_NAME)}</LAST_NAME>
                <SSN?>{fn:data($CUSTOMER/SSN)}</SSN>
                {
                    for $ADDRESS in add:ADDRESS()
                    return
                    <ADDRESS>
                        <ADDR_ID>{fn:data($ADDRESS/ADDR_ID)}</ADDR_ID>
                        <CUSTOMER_ID>{fn:data($ADDRESS/CUSTOMER_ID)}</CUSTOMER_ID>
                        <FIRST_NAME>{fn:data($ADDRESS/FIRST_NAME)}</FIRST_NAME>
                        <ZIPCODE>{fn:data($ADDRESS/ZIPCODE)}</ZIPCODE>
                        <COUNTRY>{fn:data($ADDRESS/COUNTRY)}</COUNTRY>
                    </ADDRESS>
                }
            </CUSTOMER>
        </tns:CustomerAndAddress>
};

Create the Function in Studio

1. Create a logical entity service.

   Create Your First Data Services

2. In the Overview tab, right-click at the left, right, or top, and choose Add Operation.
    
   
    
3. At Visibility, choose an access level.
   Public means the procedure can be called from the same dataspace and from client APIs; protected, only from the same dataspace; private, only from the same data service.
4. At Kind, choose read.
5. Enter a name for the function.
6. At Return Type, click Edit.
7. Click Complex Type, and choose a schema file.
8. At Kind, choose element.
9. At Occurrence, choose Zero or More.
10. Select Primary, and click OK.

See Also

How Tos

• Create a Return Type
• Test a Read Function and Simple Update

Concepts

• Data Service Types and Functions

Contact BEA | Feedback | Privacy | (c) 2008 BEA Systems